<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>bmqa_mocksession Component</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="bdedox.css" rel="stylesheet" type="text/css"/>
    <style>
      div.hanging {
        padding-left: 0.75in;
        text-indent: -0.50in;
      }
      div.unhanging {
        text-indent:     0in;
      }
      a.glossary {
        font-weight: bold;
        font-style: italic;
      }
    </style>
</head>
<!--
<body onload='searchBox.OnSelectItem(0);'>
-->
<body>

<table border=2 cellspacing=0 cellpadding=0 align=center>
<tr>
 <td valign=top align=center>
 <p align=center><b><i>Quick Links:</i></b></p>
 </td>
 <td valign=top align=center>
 <p align=center>
<a class="qindex" href="group__bmqa.html" target="_blank">bmqa</a> | <a class="qindex" href="group__bmqpi.html" target="_blank">bmqpi</a> | <a class="qindex" href="group__bmqt.html" target="_blank">bmqt</a>
 </td>
 </tr>
 </table>

  </div>
<!-- Generated by Doxygen 1.7.1 -->
<div class="navigation" id="top">
  <div class="tabs">
    <ul class="tablist">
      <li><a href="components.html"><span>Main&nbsp;Page</span></a></li>
      <li><a href="components.html"><span>Components</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div class="header">
  <div class="summary">
<a href="#namespaces">Namespaces</a>  </div>
  <div class="headertitle">
<h1>Component bmqa_mocksession<br/>
<small>
[<a class="el" href="group__bmqa.html">Package bmqa</a>]</small>
</h1>  </div>
</div>
<div class="contents">

<p>Provide a mock session, implementing <code><a class="el" href="classbmqa_1_1AbstractSession.html">bmqa::AbstractSession</a></code>.  
<a href="#_details">More...</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="namespaces"></a>
Namespaces</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">namespace &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespacebmqimp.html">bmqimp</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">namespace &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="namespacebmqa.html">bmqa</a></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<dl class="user"><dt><b>Outline</b></dt><dd><ul>
<li>
<a href="#1">Purpose</a> </li>
<li>
<a href="#2">Classes</a> </li>
<li>
<a href="#3">Description</a> <ul>
<li>
<a href="#3.1">Disclaimer</a> </li>
<li>
<a href="#3.2">Usable Components</a> </li>
<li>
<a href="#3.3">Static Helper Methods</a> </li>
<li>
<a href="#3.4">Additional Note</a> </li>
<li>
<a href="#3.5">Creating a mock session in asynchronous mode</a> </li>
<li>
<a href="#3.6">Usage</a> <ul>
<li>
<a href="#3.6.1">Example 1</a> </li>
<li>
<a href="#3.6.2">Example 2</a> </li>
</ul>
</li>
<li>
<a href="#3.7">Thread Safety</a> </li>
</ul>
</li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="purpose"></a> <a class="anchor" id="1"></a> </dd></dl>
<dl class="user"><dt><b>Purpose: </b></dt><dd>Provide a mock session, implementing <code><a class="el" href="classbmqa_1_1AbstractSession.html">bmqa::AbstractSession</a></code>. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="classes"></a> <a class="anchor" id="2"></a> </dd></dl>
<dl class="user"><dt><b>Classes: </b></dt><dd><table class="doxtable">
<tr>
<td><a class="el" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a> </td><td>mechanism to mock a <code><a class="el" href="classbmqa_1_1Session.html">bmqa::Session</a></code>  </td></tr>
<tr>
<td><a class="el" href="structbmqa_1_1MockSessionUtil.html">bmqa::MockSessionUtil</a> </td><td>utility methods to create <code>bmqa</code> events  </td></tr>
</table>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="description"></a> <a class="anchor" id="3"></a> </dd></dl>
<dl class="user"><dt><b>Description: </b></dt><dd>This component provides a mechanism implementing the <code><a class="el" href="classbmqa_1_1AbstractSession.html">bmqa::AbstractSession</a></code> protocol, for mocking a <code><a class="el" href="classbmqa_1_1Session.html">bmqa::Session</a></code> and can be used to write a test for an application that uses BMQ. The <code><a class="el" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a></code> provides all the methods that <code>Session</code> provides, with added methods to specify return codes and emitted events and expected calls. This can be used to test BlazingMQ application code without a connection to the broker. <code><a class="el" href="structbmqa_1_1MockSessionUtil.html">bmqa::MockSessionUtil</a></code> is a utility namespace providing useful methods to build <code><a class="el" href="classbmqa_1_1Event.html">bmqa::Event</a></code> objects that are typically only emitted from the broker. </dd></dl>
<dl class="user"><dt><b></b></dt><dd>The following documentation elucidates the API that this component provides and some simple use cases to get you started. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="disclaimer"></a> <a class="anchor" id="description.disclaimer"></a> <a class="anchor" id="3.1"></a> </dd></dl>
<dl class="user"><dt><b>Disclaimer: </b></dt><dd>THIS COMPONENT SHOULD ONLY BE USED IN TEST DRIVERS. IT WILL NOT WORK WITH PRODUCTION CODE. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="usable_components"></a> <a class="anchor" id="description.usable_components"></a> <a class="anchor" id="3.2"></a> </dd></dl>
<dl class="user"><dt><b>Usable Components: </b></dt><dd><ul>
<li>
<b>BMQA_EXPECT_CALL</b>: Macro to specify an expected call to a <code><a class="el" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a></code> object. This macro is used to specify which is the next expected call on the <code><a class="el" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a></code>. If an incorrect call is invoked or incorrect parameters are used, an assert will be invoked.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<b>returning</b> : Specify a return value for the expected call. This is the value that will be returned when the method on <code><a class="el" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a></code> is invoked.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<b>emitting</b> : Specify an event to be <code>emitted</code> when the expected call is invoked. The events specified are enqueued to the internal event queue and are delivered to the application when <code>emitEvent</code> is invoked.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="static_helper_methods"></a> <a class="anchor" id="description.static_helper_methods"></a> <a class="anchor" id="3.3"></a> </dd></dl>
<dl class="user"><dt><b>Static Helper Methods: </b></dt><dd><ul>
<li>
<b>createAckEvent</b> : Create an acknowledgment message event for messages posted to BMQ.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<b>createPushEvent</b> : Create a push message event for messages to be consumed from BMQ.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<b>createOpenQueueStatus</b> : Create an openQueue result (relating to an async open queue operation)  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<b>createConfigureQueueStatus</b>: Create a configureQueue result (relating to an async configure queue operation)  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<b>createCloseQueueStatus</b> : Create a closeQueue result (relating to an async close queue operation)  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd><ul>
<li>
<b>createSessionEvent</b> : Create a specified type of session event except for events related to open, close and configure queue.  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd>The static event builder specified above are typically built inside the broker but are now available to be built in the SDK. The expected use of such events is to build them and specify them to either the <code>BMQA_EXPECT_CALL</code> macro in the <code>emitting</code> parameter, or enqueued to the <code><a class="el" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a></code> directly through the <code>enqueueEvent</code> method. They can then be emitted by invoking the <code>emitEvent</code> method, which in turn would be processed through the application-provided <code><a class="el" href="classbmqa_1_1SessionEventHandler.html">bmqa::SessionEventHandler</a></code>. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="additional_note"></a> <a class="anchor" id="description.additional_note"></a> <a class="anchor" id="3.4"></a> </dd></dl>
<dl class="user"><dt><b>Additional Note: </b></dt><dd><code>MockSession</code> does not check if methods have been invoked in the correct order. The user is responsible for ensuring that the methods are invoked and events enqueued in the correct order. </dd></dl>
<dl class="user"><dt><b></b></dt><dd>The following methods do not emit events: <ul>
<li>
<code>getQueueId</code>  </li>
<li>
<code>loadMessageEventBuilder</code>  </li>
<li>
<code>loadConfirmEventBuilder</code>  </li>
<li>
<code>loadMessageProperties</code>  </li>
<li>
<code>confirmMessage</code>  </li>
<li>
<code>confirmMessages</code>  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd>Calls to the following methods do not require an expect: <ul>
<li>
<code>getQueueId</code>  </li>
<li>
<code>loadMessageEventBuilder</code>  </li>
<li>
<code>loadConfirmEventBuilder</code>  </li>
<li>
<code>loadMessageProperties</code>  </li>
</ul>
</dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="creating_a_mock_session_in_asynchronous_mode"></a> <a class="anchor" id="description.creating_a_mock_session_in_asynchronous_mode"></a> <a class="anchor" id="3.5"></a> </dd></dl>
<dl class="user"><dt><b>Creating a mock session in asynchronous mode: </b></dt><dd>The <code>MockSession</code> is created in asynchronous mode when a <code>SessionEventHandler</code> is provided to it. If it is not provided a handler, the <code>MockSession</code> is started in synchronous mode, requiring the application to call <code>nextEvent</code> to access enqueued events. A sample handler could look like this: </dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="fragment"><pre class="fragment">  <span class="keyword">class </span>MyEventHandler : <span class="keyword">public</span> bmqa::SessionEventHandler {

    <span class="keyword">private</span>:
      <span class="comment">// DATA</span>
      bsl::deque&lt;bmqa::SessionEvent&gt;    d_sessionEventsQueue;
      bsl::deque&lt;bmqa::MessageEvents&gt;   d_messageEventsQueue;
      bsl::deque&lt;bmqa::OpenQueueStatus&gt; d_openQueueResultsQueue;
      ...

    <span class="keyword">public</span>:
      <span class="comment">// MANIPULATORS</span>
      <span class="keyword">virtual</span> <span class="keywordtype">void</span> onSessionEvent(<span class="keyword">const</span> <a class="code" href="classbmqa_1_1SessionEvent.html">bmqa::SessionEvent</a>&amp; event)
      {
          bsl::cout &lt;&lt; <span class="stringliteral">&quot;Received session event &quot;</span> &lt;&lt; <span class="keyword">event</span> &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;
          <span class="comment">// some business logic, typically a switch case on</span>
          <span class="comment">// &#39;bmqt::SessionEventType&#39;</span>
          d_sessionEventsQueue.push_back(event);
      }

      <span class="keyword">virtual</span> <span class="keywordtype">void</span> onMessageEvent(<span class="keyword">const</span> <a class="code" href="classbmqa_1_1MessageEvent.html">bmqa::MessageEvent</a>&amp; event)
      {
          bsl::cout &lt;&lt; <span class="stringliteral">&quot;Received message event &quot;</span> &lt;&lt; <span class="keyword">event</span> &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;
          <span class="comment">// some business logic, typically a switch case on</span>
          <span class="comment">// &#39;bmqt::MessageEventType&#39;</span>
          d_messageEventsQueue.push_back(event);
      }

      <span class="keywordtype">void</span> onOpenQueueStatus(<span class="keyword">const</span> <a class="code" href="classbmqa_1_1OpenQueueStatus.html">bmqa::OpenQueueStatus</a>&amp; result)
      {
          bsl::cout &lt;&lt; <span class="stringliteral">&quot;Received open queue result: &quot;</span> &lt;&lt; result &lt;&lt; <span class="stringliteral">&quot;\n&quot;</span>;
          <span class="comment">// Some business logic</span>
          d_openQueueResultsQueue.push_back(result);
      }
      ...

      <a class="code" href="classbmqa_1_1SessionEvent.html">bmqa::SessionEvent</a> popSessionEvent()
      {
          BSLS_ASSERT(d_sessionEventsQueue.size() &gt; 0);
          <a class="code" href="classbmqa_1_1SessionEvent.html">bmqa::SessionEvent</a> ret(d_receivedSessionEvents.front());
          d_receivedSessionEvents.pop_front();
          <span class="keywordflow">return</span> ret;
      }

      <a class="code" href="classbmqa_1_1MessageEvent.html">bmqa::MessageEvent</a> popMessageEvent()
      {
          BSLS_ASSERT(d_messageEventsSize.size() &gt; 0);
          <a class="code" href="classbmqa_1_1MessageEvent.html">bmqa::MessageEvent</a> ret(d_receivedMessageEvents.front());
          d_receivedMessageEvents.erase(d_receivedMessageEvents.begin());
          <span class="keywordflow">return</span> ret;
      }

      <a class="code" href="classbmqa_1_1OpenQueueStatus.html">bmqa::OpenQueueStatus</a> popOpenQueueStatus()
      {
          BSLS_ASSERT(d_openQueueResultsQueue.size() &gt; 0);
          <a class="code" href="classbmqa_1_1OpenQueueStatus.html">bmqa::OpenQueueStatus</a> ret(d_openQueueResultsQueue.front());
          d_openQueueResultsQueue.erase(d_openQueueResultsQueue.begin());
          <span class="keywordflow">return</span> ret;
      }
      ...
  };
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="usage"></a> <a class="anchor" id="description.usage"></a> <a class="anchor" id="3.6"></a> </dd></dl>
<dl class="user"><dt><b>Usage: </b></dt><dd>This section illustrates intended use of this component. </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="example_1"></a> <a class="anchor" id="usage.example_1"></a> <a class="anchor" id="description.usage.example_1"></a> <a class="anchor" id="3.6.1"></a> </dd></dl>
<dl class="user"><dt><b>Example 1: </b></dt><dd>The folowing example shows a simple producer in asynchronous mode, which will start the session, open a queue, post a message to the queue, generate an ack for that message and finally stop the session (skipping over close queue because it is analogous to opening a queue). In theory, you can use <code>emitting</code> on the <code>BMQA_EXPECT_CALL</code> macro and <code>enqueueEvent</code> interchangeably, but in practice it is important to note that events from the broker are generated asynchronously, which means that they are not emitted as you call the method. You can control emission of events, however, by delaying the call to <code>emitEvent</code>. </dd></dl>
<dl class="user"><dt><b></b></dt><dd>NOTE: As with <code><a class="el" href="classbmqa_1_1Session.html">bmqa::Session</a></code>, calling <code>nextEvent</code> is meaningless in asynchronous mode. </dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span> unitTest()
  {
       <span class="comment">// Create an event handler</span>
       EventHandler eventHandler(d_allocator_p);

       <span class="comment">// The following static initializer method calls all the appropriate</span>
       <span class="comment">// static initializers of the underlying components needed for the</span>
       <span class="comment">// &#39;MockSession&#39;.  The constructor of &#39;MockSession&#39; will call it in</span>
       <span class="comment">// any case but if events need to be built outside the scope of the</span>
       <span class="comment">// creation of &#39;MockSession&#39; you will need to explicitly invoke this</span>
       <span class="comment">// static initializer method.</span>
       <span class="comment">// bmqa::MockSession::initialize(s_allocator_p);</span>

       bslma::ManagedPtr&lt;bmqa::SessionEventHandler&gt; handlerMp;
       handlerMp.load(&amp;eventHandler, 0, bslma::ManagedPtrUtil::noOpDeleter);

       <a class="code" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a> mockSession(handlerMp,
                                     <a class="code" href="classbmqt_1_1SessionOptions.html">bmqt::SessionOptions</a>(d_allocator_p),
                                     d_allocator_p);

       <a class="code" href="classbmqa_1_1QueueId.html">bmqa::QueueId</a>       queueId(<a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a>(1), d_allocator_p);
       <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a> corrId(1);

       <span class="comment">// Expect a call to start and the call emits an &#39;e_CONNECTED&#39; event.</span>
       <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, startAsync())
           .returning(0)
           .emitting(<a class="code" href="structbmqa_1_1MockSessionUtil.html#a78bc99248c9843ce2141c01ee1636688">bmqa::MockSessionUtil::createSessionEvent</a>(
                         <a class="code" href="structbmqt_1_1SessionEventType.html#aef449af38af76209352bf82f78b92529a93376e0c6edbbe6ee9354a9677235144" title="Session started.">bmqt::SessionEventType::e_CONNECTED</a>,
                         0,   <span class="comment">// statusCode</span>
                         <span class="stringliteral">&quot;&quot;</span>,  <span class="comment">// errorDescription</span>
                         d_allocator_p));

       <span class="comment">// Make a call to startAsync and emit the event that is enqueued from</span>
       <span class="comment">// that call.</span>
       ASSERT_EQ(mockSession.startAsync(), 0);

       <span class="comment">// Emit our enqueued event.  This fully sets up the session which is</span>
       <span class="comment">// now ready to use.  Typically you would have some business logic on</span>
       <span class="comment">// &#39;e_CONNECTED&#39; that makes your application ready to use.</span>
       ASSERT_EQ(mockSession.emitEvent(), <span class="keyword">true</span>);

       <span class="comment">// Our event handler internally just stores the event emitted, so pop</span>
       <span class="comment">// it out and examine.</span>
       <a class="code" href="classbmqa_1_1SessionEvent.html">bmqa::SessionEvent</a> startEvent(eventHandler.popSessionEvent());

       ASSERT_EQ(startEvent.type(), bmqt::SessionEventType::e_CONNECTED);
       ASSERT_EQ(startEvent.statusCode(), 0);

       <span class="comment">// Create the uri to your queue as you would in your application.</span>
       <span class="keyword">const</span> <a class="code" href="classbmqt_1_1Uri.html">bmqt::Uri</a> uri(<span class="stringliteral">&quot;bmq://my.domain/queue&quot;</span>);

       <span class="comment">// Initialize the queue flags for a producer with acks enabled</span>
       bsls::Types::Uint64 flags = 0;
       <a class="code" href="structbmqt_1_1QueueFlagsUtil.html#a7323252232359c20dc74334220e36786">bmqt::QueueFlagsUtil::setWriter</a>(&amp;flags);
       <a class="code" href="structbmqt_1_1QueueFlagsUtil.html#ab2668812f3b97d2dff6d2021c60ab080">bmqt::QueueFlagsUtil::setAck</a>(&amp;flags);

       <span class="comment">// We use the macro to expect a call to &#39;openQueueAsync&#39;, binding the</span>
       <span class="comment">// &#39;uri&#39; and &#39;queueId&#39; objects as well as the &#39;flags&#39; that we created.</span>
       <a class="code" href="classbmqa_1_1AbstractSession.html#a75e7237336027136889801133334b72d">bmqa::MockSession::OpenQueueCallback</a> openQueueCallback =
           bdlf::BindUtil::bind(&amp;EventHandler::onOpenQueueStatus,
                                &amp;eventHandler,
                                bdlf::PlaceHolders::_1); <span class="comment">// result</span>

       <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession,
                        openQueueAsync(uri1,
                                       flags,
                                       openQueueCallback));
       <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession,
                        openQueueAsync(uri, flags, openQueueCallback));

       <span class="comment">// Now that we have set our expectations we can try to open the queue.</span>
       mockSession.openQueueAsync(uri1, flags, openQueueCallback);

       <span class="comment">// Since the application may not have direct access to the queue, we</span>
       <span class="comment">// need to get the &#39;queueId&#39; from the session.  We can then bind this</span>
       <span class="comment">// retrieved &#39;queueId&#39; to the &#39;e_QUEUE_OPEN_RESULT&#39; session event and</span>
       <span class="comment">// enqueue it to the &#39;MockSession&#39;.</span>
       <span class="comment">// Note: You can only get the &#39;queueId&#39; after &#39;openQueue&#39; or</span>
       <span class="comment">//       &#39;openQueueAsync&#39; has been invoked on the session.</span>
       <a class="code" href="classbmqa_1_1QueueId.html">bmqa::QueueId</a>         queueId1(corrId1);
       <a class="code" href="classbmqa_1_1OpenQueueStatus.html">bmqa::OpenQueueStatus</a> openQueueResult =
           <a class="code" href="structbmqa_1_1MockSessionUtil.html#a09dc823ead6e2c8125604cf4590d4e9f">bmqa::MockSessionUtil::createOpenQueueStatus</a>(
                       queueId1,
                       <a class="code" href="structbmqt_1_1OpenQueueResult.html#ad9ced6521b110ebf4fff8dcac28dad1ca2833ab3973cc9bc6a1cbff2d95856de4">bmqt::OpenQueueResult::e_TIMEOUT</a>,  <span class="comment">// statusCode</span>
                       <span class="stringliteral">&quot;Local Timeout&quot;</span>,                   <span class="comment">// errorDescription</span>
                       d_allocator_p);
       mockSession.enqueueEvent(openQueueResult);

       <span class="comment">// We just enqueued a &#39;bmqa::OpenQueueStatus&#39; to be emitted.  We can</span>
       <span class="comment">// emit it using &#39;emitEvent&#39;.</span>
       ASSERT_EQ(mockSession.emitEvent(), <span class="keyword">true</span>);

       <span class="comment">//  Pop out this event from the handler and examine it.</span>
       <a class="code" href="classbmqa_1_1OpenQueueStatus.html">bmqa::OpenQueueStatus</a> result = eventHandler.popOpenQueueStatus();
       ASSERT_EQ(result, openQueueResult);

       <span class="comment">// On emission of &#39;bmqa::OpenQueueStatus&#39;, the queue is fully open and</span>
       <span class="comment">// we can now post to it.</span>
       <a class="code" href="classbmqa_1_1MessageEventBuilder.html">bmqa::MessageEventBuilder</a> builder;
       mockSession.loadMessageEventBuilder(&amp;builder);

       <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, post(builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a4998ec39691c9f90d639b554d681a782">messageEvent</a>()))
           .returning(0);

       <span class="comment">// Use the builder to build a mesage event and pack it for the queue</span>
       <span class="comment">// that has been opened.  If you try to pack the message for an</span>
       <span class="comment">// invalid or closed queue, packing the message will fail. This has</span>
       <span class="comment">// been elided for brevity.</span>

       <span class="comment">// Now that the event has been built we can &#39;post&#39; it to BMQ.</span>
       ASSERT_EQ(mockSession.post(builder.<a class="code" href="classbmqa_1_1MessageEventBuilder.html#a4998ec39691c9f90d639b554d681a782">messageEvent</a>()), 0);

       <span class="comment">// Simply creating a blob buffer factory on the stack to be used by</span>
       <span class="comment">// &#39;createAckEvent&#39;.  Typically you would have one for the component.</span>
       bdlbb::PooledBlobBufferFactory bufferFactory(4 * 1024, d_allocator_p);

       <span class="comment">// The method &#39;createAckEvent&#39; takes a vector of &#39;AckParams&#39; to</span>
       <span class="comment">// specify multiple acks per event, but here we are only acknowledging</span>
       <span class="comment">// 1 message.  Specify a positive ack with &#39;e_SUCCESS&#39; here but you</span>
       <span class="comment">// can specify any from &#39;bmqt::AckResult::Enum&#39;.</span>
       bsl::vector&lt;bmqa::MockSessionUtil::AckParams&gt; acks(d_allocator_p);
       acks.emplace_back(<a class="code" href="structbmqt_1_1AckResult.html#a1ab5de366be811debfb50e08dbfd7132afefd2be6b31bf56ed46c8dc11fe471dc">bmqt::AckResult::e_SUCCESS</a>,
                         <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a>(1),
                         <a class="code" href="classbmqt_1_1MessageGUID.html">bmqt::MessageGUID</a>(), <span class="comment">// Real GUID needed if you want</span>
                                              <span class="comment">// to record ack messages.</span>
                         <a class="code" href="classbmqa_1_1QueueId.html">bmqa::QueueId</a>(1));

       <span class="comment">// Enqueuing ack event to be emitted.  We use the helper function</span>
       <span class="comment">// &#39;createAckEvent&#39; to generate this event.</span>
       mockSession.enqueueEvent(<a class="code" href="structbmqa_1_1MockSessionUtil.html#a60813af958e6323c74374e8567721f40">bmqa::MockSessionUtil::createAckEvent</a>(
                                                             acks,
                                                             &amp;bufferFactory,
                                                             d_allocator_p));

       <span class="comment">// Emit the enqueued ack event.</span>
       ASSERT_EQ(mockSession.emitEvent(), <span class="keyword">true</span>);

       <span class="comment">// As we did earlier, pop it out and examine.</span>
       <a class="code" href="classbmqa_1_1MessageEvent.html">bmqa::MessageEvent</a> ackEvent(eventHandler.popMessageEvent());
       ASSERT_EQ(ackEvent.type(), bmqt::MessageEventType::e_ACK);
       <a class="code" href="classbmqa_1_1MessageIterator.html">bmqa::MessageIterator</a> mIter = ackEvent.messageIterator();
       mIter.nextMessage();
       ASSERT_EQ(mIter.message().ackStatus(), bmqt::AckResult::e_SUCCESS);

       <span class="comment">// This is a simple test.  After posting our message and receiving the</span>
       <span class="comment">// ack, we are now shutting down our application.  Therefore we expect</span>
       <span class="comment">// a &#39;stopAsync&#39; call.</span>
       <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, stopAsync());

       <span class="comment">// Now make a call to &#39;stopAsync&#39; to stop our session.</span>
       mockSession.stopAsync();

       <span class="comment">// Here we are enqueuing an &#39;e_DISCONNECTED&#39; event as you would</span>
       <span class="comment">// receive from the broker on a successful shutdown.</span>
       mockSession.enqueueEvent(<a class="code" href="structbmqa_1_1MockSessionUtil.html#a78bc99248c9843ce2141c01ee1636688">bmqa::MockSessionUtil::createSessionEvent</a>(
                                      <a class="code" href="structbmqt_1_1SessionEventType.html#aef449af38af76209352bf82f78b92529a45dce28857e18a5788c4fcfa9a74ee64" title="Session terminated.">bmqt::SessionEventType::e_DISCONNECTED</a>,
                                      0,   <span class="comment">// statusCode</span>
                                      <span class="stringliteral">&quot;&quot;</span>,  <span class="comment">// errorDescription</span>
                                      d_allocator_p));
       ASSERT_EQ(mockSession.emitEvent(), <span class="keyword">true</span>);

       <span class="comment">// Our event handler internally just stores the event emitted, so pop</span>
       <span class="comment">// it out and examine.</span>
       <a class="code" href="classbmqa_1_1SessionEvent.html">bmqa::SessionEvent</a> stopEvent(eventHandler.popSessionEvent());
       ASSERT_EQ(stopEvent.type(), bmqt::SessionEventType::e_DISCONNECTED);
       ASSERT_EQ(stopEvent.statusCode(), 0);

      <span class="comment">// The corresponding pendant operation of the &#39;initialize&#39; which would</span>
      <span class="comment">// need to be called only if &#39;initialize&#39; was explicitly called.</span>
      <span class="comment">// bmqa::MockSession::shutdown();</span>
   }
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="example_2"></a> <a class="anchor" id="usage.example_2"></a> <a class="anchor" id="description.usage.example_2"></a> <a class="anchor" id="3.6.2"></a> </dd></dl>
<dl class="user"><dt><b>Example 2: </b></dt><dd>The folowing example shows a consumer in synchronous mode, which will start the session, generate a push message (simulating the broker), confirm the message and then stop the session. Additionally, this test case also sets all expectations up front before running the code, as this is the alternate way of writing your test driver. </dd></dl>
<dl class="user"><dt><b></b></dt><dd>NOTE: Using <code>enqueue</code> or <code>emitEvent</code> on <code><a class="el" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a></code> or <code>emitting</code> on the <code>BMQA_EXPECT_CALL</code> macro in synchronous mode is meaningless. </dd></dl>
<dl class="user"><dt><b></b></dt><dd><div class="fragment"><pre class="fragment">  <span class="keywordtype">void</span> unitTest()
  {
      <span class="comment">// MockSession created without an eventHandler.</span>
      <a class="code" href="classbmqa_1_1MockSession.html">bmqa::MockSession</a> mockSession(<a class="code" href="classbmqt_1_1SessionOptions.html">bmqt::SessionOptions</a>(d_allocator_p),
                                    d_allocator_p);

      <span class="comment">// The following static initializer method calls all the appropriate</span>
      <span class="comment">// static initializers of the underlying components needed for the</span>
      <span class="comment">// &#39;MockSession&#39;.  The constructor of &#39;MockSession&#39; will call it in</span>
      <span class="comment">// any case but if events need to be built outside the scope of the</span>
      <span class="comment">// creation of &#39;MockSession&#39; you will need to explicitly invoke this</span>
      <span class="comment">// static initializer method.</span>
      <span class="comment">// bmqa::MockSession::initialize(s_allocator_p);</span>

      <span class="comment">// Create simple queueIds and corrIds</span>
      <a class="code" href="classbmqa_1_1QueueId.html">bmqa::QueueId</a>       queueId(1);
      <a class="code" href="classbmqt_1_1CorrelationId.html">bmqt::CorrelationId</a> corrId(1);

      <span class="comment">// Create the uri to your queue as you would in your application.</span>
      <a class="code" href="classbmqt_1_1Uri.html">bmqt::Uri</a> uri(<span class="stringliteral">&quot;bmq://my.domain/queue&quot;</span>);

      <span class="comment">// Expecting that &#39;startAsync&#39; will be called on the MockSession.</span>
      <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, startAsync())
          .returning(0);

      <span class="comment">// Simply creating a blob buffer factory on the stack to be used by</span>
      <span class="comment">// &#39;createAckEvent&#39;.  Typically you would have one for the component.</span>
      bdlbb::PooledBlobBufferFactory bufferFactory(4 * 1024, d_allocator_p);

      <span class="comment">// We then expect that &#39;nextEvent&#39; will be called to return the</span>
      <span class="comment">// &#39;e_CONNECTED&#39; event from the broker</span>
      <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, nextEvent(bsls::TimeInterval()))
          .returning(<a class="code" href="structbmqa_1_1MockSessionUtil.html#a78bc99248c9843ce2141c01ee1636688">bmqa::MockSessionUtil::createSessionEvent</a>(
                         <a class="code" href="structbmqt_1_1SessionEventType.html#aef449af38af76209352bf82f78b92529a93376e0c6edbbe6ee9354a9677235144" title="Session started.">bmqt::SessionEventType::e_CONNECTED</a>,
                         <a class="code" href="classbmqt_1_1CorrelationId.html#a227367a2269c2b52955b7593ef6add6b">bmqt::CorrelationId::autoValue</a>(),
                         0,   <span class="comment">// errorCode</span>
                         <span class="stringliteral">&quot;&quot;</span>,  <span class="comment">// errorDescription</span>
                         d_allocator_p));
          <span class="comment">// Note that we use an &#39;autoValue&#39; for correlationId because it&#39;s</span>
          <span class="comment">// irrelevant for a &#39;CONNECTED&#39; event.</span>

       <span class="comment">// Initialize the queue flags for a consumer</span>
       bsls::Types::Uint64 flags = 0;
       <a class="code" href="structbmqt_1_1QueueFlagsUtil.html#a1267cc4314d3431ce8823efbc5e25424">bmqt::QueueFlagsUtil::setReader</a>(&amp;flags);

      <span class="comment">// We use the macro to expect a call to &#39;openQueueSync&#39;, binding the</span>
      <span class="comment">// &#39;uri&#39; and &#39;queueId&#39; objects as well as the flags that we created.</span>
      <span class="comment">// Note that the &#39;queueId&#39; object will be modified as &#39;openQueueSync&#39;</span>
      <span class="comment">// takes it as an output parameter.</span>
      <a class="code" href="classbmqa_1_1OpenQueueStatus.html">bmqa::OpenQueueStatus</a> expectedResult =
          <a class="code" href="structbmqa_1_1MockSessionUtil.html#a09dc823ead6e2c8125604cf4590d4e9f">bmqa::MockSessionUtil::createOpenQueueStatus</a>(
                       queueId,
                       <a class="code" href="structbmqt_1_1OpenQueueResult.html#ad9ced6521b110ebf4fff8dcac28dad1ca3dca190a8145bd79547879b6b4efe164">bmqt::OpenQueueResult::e_SUCCESS</a>,  <span class="comment">// statusCode</span>
                       <span class="stringliteral">&quot;&quot;</span>,                                <span class="comment">// errorDescription</span>
                       d_allocator_p);
      <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, openQueueSync(&amp;queueId, uri, flags))
          .returning(expectedResult);

      <span class="comment">// Build our incoming message event.</span>
      bsl::vector&lt;bmqa::MockSessionUtil::PushMessageParams&gt; pushMsgs(
                                                              d_allocator_p);
      bdlbb::Blob payload(&amp;bufferFactory, d_allocator_p);
      bdlbb::BlobUtil::append(&amp;payload, <span class="stringliteral">&quot;hello&quot;</span>, 6);

      <span class="keyword">const</span> <span class="keywordtype">char</span>        guidHex[] = <span class="stringliteral">&quot;00000000000000000000000000000001&quot;</span>;
      <a class="code" href="classbmqt_1_1MessageGUID.html">bmqt::MessageGUID</a> guid;
      guid.<a class="code" href="classbmqt_1_1MessageGUID.html#a76a94bb992e42149e950273ae96e2986">fromHex</a>(guidHex);

      <a class="code" href="classbmqa_1_1MessageProperties.html">bmqa::MessageProperties</a> properties;
      mockSession.loadMessageProperties(&amp;properties);

      <span class="comment">// For each message that we are supposed to receive from the broker,</span>
      <span class="comment">// we need to specify the payload, the queueId, a guid (the hex is</span>
      <span class="comment">// random but unique within your test driver) and properties which</span>
      <span class="comment">// could be empty.</span>
      pushMsgs.emplace_back(payload, queueId, guid, properties);
      <a class="code" href="classbmqa_1_1Event.html">bmqa::Event</a> pushMsgEvent = <a class="code" href="structbmqa_1_1MockSessionUtil.html#af827722f36d2fabd968929767d60ff27">bmqa::MockSessionUtil::createPushEvent</a>(
                                                              pushMsgs,
                                                              &amp;bufferFactory,
                                                              d_allocator_p);
      <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, nextEvent(bsls::TimeInterval()))
          .returning(pushMsgEvent);

      <span class="comment">// Next we expect a call to &#39;confirmMessages&#39;, to confirm the 1 message</span>
      <span class="comment">// that we received from the broker.</span>
      <a class="code" href="classbmqa_1_1ConfirmEventBuilder.html">bmqa::ConfirmEventBuilder</a> confirmBuilder;
      mockSession.loadConfirmEventBuilder(&amp;confirmBuilder);
      <a class="code" href="bmqa__mocksession_8h.html#abe2652fa6d696e03dec9bf44e4e731c9">BMQA_EXPECT_CALL</a>(mockSession, confirmMessages(&amp;confirmBuilder))
          .returning(0);

      <span class="comment">// Expectations have been set up.  Now we run the code.</span>
      <span class="comment">// &#39;startAsync&#39; is the first call.  We expect it to return 0 and we</span>
      <span class="comment">// expect &#39;nextEvent&#39; to return the &#39;e_CONNECTED&#39; session event.</span>
      <span class="keywordtype">int</span> rc = mockSession.startAsync();
      ASSERT_EQ(rc, 0);
      <a class="code" href="classbmqa_1_1SessionEvent.html">bmqa::SessionEvent</a> startEvent = mockSession.nextEvent(
                                                        bsls::TimeInterval())
          .sessionEvent();
      ASSERT_EQ(startEvent.<a class="code" href="classbmqa_1_1SessionEvent.html#a57c7930a474e344c707b64c0b1cdd075">type</a>(), bmqt::SessionEventType::e_CONNECTED);
      ASSERT_EQ(startEvent.<a class="code" href="classbmqa_1_1SessionEvent.html#a8ab036e14cc1c858c59110a76e0997eb">statusCode</a>(),       0);
      ASSERT_EQ(startEvent.<a class="code" href="classbmqa_1_1SessionEvent.html#a504e8845e244fde7b62add064deb89ad">errorDescription</a>(), <span class="stringliteral">&quot;&quot;</span>);

      <span class="comment">// Next we expect a call to &#39;openQueue&#39; to open the queue.</span>
      <a class="code" href="classbmqa_1_1OpenQueueStatus.html">bmqa::OpenQueueStatus</a> result = mockSession.openQueueSync(&amp;queueId,
                                                               uri,
                                                               10);
      ASSERT_EQ(result, expectedResult);

      <span class="comment">// Now our call to &#39;nextEvent&#39; will generate a push message from the</span>
      <span class="comment">// broker, which we will then go on to confirm.</span>
      <a class="code" href="classbmqa_1_1MessageEvent.html">bmqa::MessageEvent</a> pushMsgEvt(mockSession.nextEvent(
                                                        bsls::TimeInterval())
                                                            .messageEvent());
      ASSERT_EQ(pushMsgEvt.type(), bmqt::MessageEventType::e_PUSH);

      <span class="comment">// Now that we have received a push message which has yet to be</span>
      <span class="comment">// confirmed, we can confirm that 1 unconfirmed message exists.</span>
      ASSERT_EQ(mockSession.unconfirmedMessages(), 1U);

      <span class="comment">// Since there is only 1 message in our message event, we dont have to</span>
      <span class="comment">// iterate over the event but in reality you will want to iterate over</span>
      <span class="comment">// each message and add it to the confirm builder.</span>
      <a class="code" href="classbmqa_1_1MessageIterator.html">bmqa::MessageIterator</a> mIter = pushMsgEvt.messageIterator();
      mIter.nextMessage();
      confirmBuilder.<a class="code" href="classbmqa_1_1ConfirmEventBuilder.html#a29309e053c41d827949ec7c4e0e1fbaf">addMessageConfirmation</a>(mIter.message());
      ASSERT_EQ(confirmBuilder.<a class="code" href="classbmqa_1_1ConfirmEventBuilder.html#aabd0134cd8983b0ae129926095d40e0c">messageCount</a>(), 1);

      <span class="comment">// Confirm the messages using the builder that has been populated.</span>
      rc = mockSession.confirmMessages(&amp;confirmBuilder);
      ASSERT_EQ(rc, 0);

      <span class="comment">// Voila! We now have no unconfirmed messages.</span>
      ASSERT_EQ(mockSession.unconfirmedMessages(), 0u);
      <span class="comment">// &#39;stop&#39; has been elided for brevity and is analogous to &#39;start&#39;</span>

      <span class="comment">// The corresponding pendant operation of the &#39;initialize&#39; which would</span>
      <span class="comment">// need to be called only if &#39;initialize&#39; was explicitly called.</span>
      <span class="comment">// bmqa::MockSession::shutdown();</span>
  }
</pre></div> </dd></dl>
<dl class="user"><dt><b></b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd><a class="anchor" id="thread_safety"></a> <a class="anchor" id="description.thread_safety"></a> <a class="anchor" id="3.7"></a> </dd></dl>
<dl class="user"><dt><b>Thread Safety: </b></dt><dd>THREAD SAFE. </dd></dl>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Thu Jun 15 2023 11:58:51 by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
</body>
</html>
